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FOREWORD

This Indian Standard which is identical with IS0 9127 : 1988 `Information processing systems - User documentation and cover information for consumer software packages' issued by the International Organization for Standardization ( IS0 ) was adopted by the Bureau of Indian Standards on the recommendations of Information Systems and Software Sectional Committee ( LTD 33 ) and approval of the Electronics and Telecommunication Division Council. In the adopted standard certain those used in Indian Standards. terminology and conventions Attention is particularly drawn Standard' appear referring standard are however not to th? following: to this standard, is referred to. identical to

Wherever the words `International be read as `Indian Standard', In this Indian Standard, place the following: International the following

they should Read in its

international

Standard

Indian Standard IS 13394 : 1992 Guidelines for the documentation of computer-based application systems for information processing ( Identical )

IS0 6592 Information processing - Guidelines for the documentation of computer-based application systems
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Indian

Standard

USER DOCUMENTATION AND COVER INFORMATION FOR CONSUMER SOFTWARE PACKAGES FCR INFORMATION PROCESSING SYSTEMS
0 Introduction
software packages are ready-made Typically packages sold tation which describes the content of the software as

opposed Consumer off-the-shelf pre-wrapped The to the consumer. the software is sold

to its use. Manufacturers

produce

this documen-

tation in order to be able to adequately support the software, but in order to protect their proprietary interests, they will not normally release it to the consumer. does not give guidance Standard on how the given of an

with its user documentation. provided in the user uocumentation on the

information

This International information to information individual

Standard

cover of the package is often the only means whereby the manufacturer or marketing organization can communicate with the consumer software and uset.

should be presented, in this International content

nor does the ordering of the documentation

imply a prescribed

It is therefore vitally irnportant that sufto use the

order for the information package. Standard

ficient information

is given to enable the consumer

successfully. This International is applicable to software packages edusold off-the-shelf to consumers cational and home use. for business, scientific,

1

Scope

and field

of application

This International Standard describes the user documentation and cover information supplied with consumer software packages

:

2
IS0

References
6592, Information processing Guidelines for the

-they

User documentation provides users with all the information Typically this the form of one or more manuals

documentation This documentation need documentation to install and run the software. takes inside the wrapping. IS0

of computer-based languages

application PASCAL.

systems.

7185, Programming

included with the software bought the package. User documentation national Standard. ~~ Cover information

As a result,

users are not able to consult the manual(s)

until they have

3
is described in section one of this Inter-

Definitions
of this International Standard the following

For the purpose definitions apply

:

This is information package. decide on the qulremerits.

given on the external of the

wrapping

of the to re-

Its purpose is to enable prospective applicability software

purchasers to their

32.1 consumer software package: A software product designed and sold to carry out identified functions; the software and its associated a unit. documentation are packaged for sale as

Covet information national Standard. This InternatIonal Matketiny

is described

In section two of this Inter 3.2.2 consumer: package. The organization or person who buys the software

Standard literature. and

does not cober 3.2.3 leaflets whose purpose is to pro 3.2.4 software of the software ;1r14 data documcntatlnn required the software, i.e the documen3.2.5 marketing organization: rnarkets the sofhvare package. manufacturer: package. The organization which develops tht: end user; The person who uses the software package

mote .-

The brochures the package. Technical

descnptions

All the system, program to malnfain aricl entlanre

Phc: oryanlzat!on

whictl
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3.2.6 supplier: The organization which sells the software package to the consumer.

4

Categories

of information
three categories of

Throughout information

this International Standard have been identified :

3.2.7

software

support:

ware and its associated

The act of maintaining the softdocumentation in a functional state.

al

Essential Information supplied with every package;

NOTE - Software support may be given by the manufacturer, marketing orgenization, supplier or other organization. In special contractually-agreed cases, consumers may be permitted to maintain or enhance the software themselves.

b)

Conditional Information relevant; supplied with every package to which it is

c) 3.2.6 environment: The configuration(s) software in which the software operates. For example, software the type(s) of computer, of hardware and

Optional Information supplied at the discretion turer or marketing organization. of the manufac-

operating

system, other is designed.

and peripherals

for which the software

Annotations (ESS), (CON) and (OPT) identify ditional and optional information respectively.

essential,

con-
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Section
5 Purpose

one

:

User documentation
6.1.4 Dates (ES!9

(ESS)

The purp~.~e of user documentation is to provide the end user with sufficient information for a clear understanding of
a) the purpose, functions and characteristics of the soft-

The release date of the original and current given.

versions shall be

6.1.6

Manufacturer

or marketing

organization

(ESS)

ware; b) c) how to install and use the software; contractual rights and responsibilities. NOTE ~ It is recommended that identification
items 6.1.1 to 6.1.5 be

The name and address of the manufacturer or the organization which markets the software package shall be given.

The documentation shall include reference documentation, for day-to-day use with the software. Optionally it may include teaching documentation, designed to teach users how to use the software.

displayed to the user whenever the software is loaded. Identification information displayed on the screen must be consistent with the identi fication information yven in the reference documentation.

( based information

It may also include cards, booklets or screengiving a summary of the operating instrue

tions and commands. Where necessary, supplements to the documentation may be

6.1.6

Key words (OPT)

issued; for example

:
errata; but not covered errors in the software of known consequences.

Key words or descriptors which characterize the package and which could be used for indexing or retrieval purposes shall be given. For example; "word processing", "spreadsheet", "database management", "simulation game".

-.~ documentation
lists of identified product,

with descriptions

6.1.7

Language

(OPT) user interface (for example and for the Japanese,

Documentation

may be supplied

as hard copy or on an elec-

The language French,

used for the software

trdnic or other medium.

user documentation English).

shall be identified

6

Reference

documentation

(ESS)
6.2 Components

of the package

(ESS)

Reference

documentation

shall give a sufficiently

clear and

comprehensive account to permit the end user to set up, install and use the software successfully. Where relevant, examples and illustrations shall be given and any abbreviations and symbols used in the documentation shall be defined. Instructions shall also be included on how to use the reference

6.2.1

Items supplied (ESS)
in the package (for example disks,

All physical items supplied cassettes, manuals, and quantity. Where relevant, the contents supplied

etc.) shall be listed and identified

by name

of the physical items (for example the docuetc.) shall be identified.

documentation.

the programs ments included

on the disks or cassettes,

in the manuals,

6.1
6.1.1

identification Package

of the package

(ESS)
6.2.2 Associated items (CON)

name and code (ESS)
which identifies the package and subtitle Any associated software, hardware or documentation which may be relevant but which is not included with the package shall be briefly described. The supplier details and order number of any such item shall also be given.

The title or name which indicates or reference number

its functions

shall be given.

The product code

of the package

shall also be given.

6.1.2

Variant

(CON1

6.3
Additional identification for any package having two or more equipment or current variants (for example for operating system) shall be given. different

Functional

description

of the software
(ESS)

(ESS)

6.3.1

Purpose and field of application

6.1.3

Version

(CON) of the software, where applicable, system

The purpose of the software and the functions It performs be described. The extent of its functions shall be clarified, if necessary, any related functions Where the software be identified.

shall and,

that it does not perform shall consists of more than one tit each component pro-

The version

identification

together with an explanation shall be given.

of the version numbering

program, the purpose and function(s) gram shall be described.

3
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Examples given.

of the field of application

of the software

shall be

6.3.5

Security

(CON)

Any security facilities provided to permit the user to protect the If necessary, the special and distinguishing features of the softsoftware or its component programs and data from unauthorware, planned future revisions, etc. shall be described. ized access shall be described. Any audit features and data backup facilities shall also be

6.3.2 a)

Environment Hardware

(ESSI (ESS)

described.

requirements

6.4
6.4.1

installing

the

software

MS1

The hardware configuration(s) needed to run the software, including memory requirements, shall be specified. If appropriate, reference shall be made to corresponding b) Software documentation. requirements variants, (CON) versions and dates of any other

Installation

(ESS) for the installation of the software

Any necessary

information

b; the end user, describing all actions necessary to introduce the software into its operating environment, for example connecting a printer, ente!ing a printer master file data, running test software, specification, entering etc., shall be given.

The names,

software needed to run the software, with reference to the corresponding documentation, shall be given. 6.4.2 c) Communications requirements (CON) A description The communications described. interface to other systems shall be shall be provided on how to create backup copies if backup copies are permitted. of the software, Creating backup copies (CON)

The protocol used shall be identified and any necessary associated information given.

6.4.3

Software

modification

(CON]

The character set or communications code used shall be identified and any exceptions or special codes listed. d) Other requirements Any other scribed. (CON) requirements shall be de-

If the user environments

has to modify the software for particular or usages, the necessary information for this to

be done shall be given.

6.5

Using the software
information

(ESS)
covering

environmental

Complete

for the use of the software,

a)
6.3.3 a) Characteristics Performance Quantitative performance b) (CON) characteristics information (CON) such as b) c) d)

preparation

for use; and data;

input commands software

functions;

for typical examples,

the resulting output: and remedial and recovery

data and level of accuracy,

shall be given. e) fault and error messages, actions:

Program size (OPT1 The total program size in commonly stated (for example used units shall be

shall be given. Preparation, input, processing, output and errors may be described function by function or collectively, as appropriate. Typical examples to help the user understand the operation of

bytes, lines of source code).

c)

Processing speed (OPT) Information on processing speed (for example speed of

compilation, sorting time, communications speed, retrieval time, response time) shall be provided.

the software, including sample listings and displays of data and results shall be given.

6.3.4

Restrictions

ICON) or its components

6.5.1

Loading

the software

IESS)

Any restrictions

on the use of the software

programs shall be specified. It shall be stated whether the software is copy-protected.

InstructIons for loading the software into the cdmputer shall be given. Where preliminary actions are required, such as loading an operating system, instructions shall be provided or reference made to associated documentation.

4
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6.6.2 Control instructions, (ESS) a)

commands

or language rules

Any restrictions, for example maximum number of records per file, maximum number of files per disk, shall be described. 6.6.4 Processing (CON1

Control instructions and commands (ESS) The format and function of all control instructions or commands shall be clearly specified. Any restrictions on their use, such as mode of operation, input conditions and input sequences, shall also be specified.

b)

Output messages (ES!9 The messages displayed in response to control instructions or commands shall be listed. If the messages are not self-explanatory, their meaning shall be described. Any actions to be taken by the user in response to the messages shall also be described.

A brief description of functions carried out by the software in response to input commands, instructions and data shall be given, if necessary, for the user's understanding of the operation of the software. 6.6.6 Errors and faults (ESS)

All errors and fault conditions, and associated messages shall be described. All remedial actions for all errors and faults shall also be given. 6.8 Software technical information (CON)

cl

Programming language rules (CON) For compilers the rules of the language shall be described by reference to associated documentation (for example IS0 7185 for PASCAL).

For some types of packages, for example scientific software, it may be necessary to give technical information relating to the software, for example language used, software structure, algorithms used, etc. 6.6.1 Language (CON)

6.53 a)

Data (ESSI Input data (CON) The content, logical structure and format of the input data, including the meaning of each element, shall be described. Any dependence of the data on particular properties of the data medium shall also be described. If other equipment or software is required to prepare input data for the software, for example for the creation of files, the requirements shall be fully specified.

If the user needs this information, for example to combine the product with other software, the programming language shall be specified preferably by reference to the appropriate standard. Additionally, the name, variant, version and supplier of the compiler or interpreter shall be given. It shall be stated whether any exceptions to the language standard have been adopted. 6.6.2 Problem solution principles and algorithms (OPT)

b)

Auxiliary data (CON) Any auxiliary data required for the operation of the software, for example a dictionary for word processing software, shall be described.

cl

Output data fESSI
The content and format of displays, printouts and any other form of output data shall be described. Illustrations of sample output shall be given.

The theoretical principles, methods of solution and algorithms used in connection with the specified functions and with the structural organization of the program(s) shall be described. Relevant literature references shall also be given. Details of any special interpretation of characters or combination of characters applicable to the solution of the problem, especially concerning prefixes, suffixes, signs, accuracy, rounding, coordinate systems and value ranges shall be given. 6.6.3 Software structure (OPT)
units (for example storage areas) program, be de-

d)

Intermediate The content

data (CON) and format of any intermediate data shall The organization modules, scribed. of the software common segments, shall

be described, when necessary, for the user's understanding of the operation of the software. e) Restrictions on data (CON)

The presentation Any restrictions on data, for example limit on number tree structure size, shall be described. f) Data storage (CON) File and record formats shall be described if necessary,

may be made graphically, diagram, or by an

for example

by a

appropriately

structured

textual description, and may contain the unit names, their entry points and interfaces, as well as their inter-relationships.

6.7

Testing

(OPT)
with

for the user's understanding of the operation of the software. It shall be stated whether the formatting permits use of the files and records by other software.

Any methods used to test the software package functions, sample inputs and expected outputs, shall be described.

5
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6.8
6.6.1

Contractual
Warranty

information

(ESSI

6.11

End users' comments

,(OPTI

or guarantee

(ESS) or

Copyright conditions and the terms of the warranty guarantee shall be stated. The guarantor shall be named. 6.6.2 Legal rights and responsibilities (ESS)

A means whereby end users may comment on the accuracy and usefulness of the documentation shall be included. This may take the form of a preprinted, prepaid card to be returned to the manufacturer or marketing organization.

7

Training

documentation

(OPT)

The manufacturer's legal responsibilities and the consumer's rights, including

The purpose of training documentation is to give a step by step introduction to the use of the package for new or inexperienced users. For the simpler types of software, the contents of the reference documentation may be sufficiently simple to meet this requirement. However, for software with a more complex user interface, special training documentation may be advisable. As the purpose of training documentation is to introduce users to the software, it is not necessary to describe the user interface in complete detail. Sufficient guidance should be provided to give users practice and confidence in using the software, and to bring them to the point where they are able to use the reference documentation successfully. As an alternative to, or in addition to, printed documentation, training may be provided in an on-line form (for example as software and sample data supplied on and loaded from disk). The manufacturer, marketing organization or supplier may also offer personal training.

a)
b) cl dl

training and related assistance; software support (correction of faults, etc.); quality assurance (product testing, etc. 1; availability of source code;

shall be described. The address of the organizationW or person(s) responsible for the above shall also be given. 6.6.3 Standards and laws (OPT)

Any applicable standards followed, for example IS0 6!X?, shall be referenced. If not in full conformity, the degree or level to which the standard is followed shall be stated.

6.9

Glossary

(CON)

8

Quick

reference

documentation

(OPT)

A glossary of technical or other specialist terminology with which the user is unlikely to be familiar shall be included.

6.10

Index (CON)

Summaries of operating instructions (commands, error messages, etc.) printed on cards or in small booklets are valuable to the experienced user, as a supplement to the reference documentation. The provision of on-screen menus and "help" facilities is also recommended.

An index of the contents of the reference documentation shall be given.
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Section two:
9 Purpose

Cover information

(ESS)

10.5
Cover package purpose plicability information is information potential attached externally to the Its and readable is to permit by the consumer before purchase.

Output

(OPT)
for example laser printer, and format(s),

The output device(s), for example

purchasers

to assess the ap-

display formats,

shall be defined

or illustrated.

of the package

to their requirements.

10.6

Restriction

on data

or files

(CON)
maximum 10,000

Any restrictions

on data or files, for example

10 10.1

Content Package identification (ESSI

records per file shall be indicated.

10.7

Instructions

for use (OPT)
shall be given on how to use the package.

The title or name which identifies the package and a subtitle which indicates its function shall be given. The date of release shall also be provided. Variant and the and version name information if required which shall be provided manufactures or

A brief description

10.8

Supplementary
methods, planned

information

(OPT)
features of

The derivation, the software,

special and distinguishing

of the

organization

revisions,

etc., shall be indicated.

markets the package

shall also be given.

10.9
Key words or descriptors Where interface applicable, shall be listed.

Contractual

information

(CON)
shall be specified,

Contractual the language in which are written the software user including

information,

as applicable,

:

and the documenration

shall be identified.

10.2
The

copyright; licencing warranty terms and condittins or guarantee terms. of use;

Purpose
purpose

and field

of application
of the package enables the

(ESSI
shall be briefly to decide can be used.

-

and functions that

described whether,

in a way

consumer

and within what limits, the package

10.10

Customer

service

address

(OPT)

The name,

address and telephone

number of the organization shall be given.

10.3 10.3.1

Environment Hardware

(ESSI requirements (ESS)

or persons responsible

for package support

10.11

Items

supplied

(ESS)

The hardware configuration needed to run the software shall be specified and memory requirements indicated.

The physical items which constitute the package shall be listed, for example flexible disk cartridge, manual, keyboard template.

10.12
10.32 The

Standards

and laws

(OPT)
shall be referenced with. as well

Software
name,

requirements
dates and

(CON)
variants of other software Any applicable standards followed as any laws or statutes conformed

versions,

needed to run the package

shall be given.

10.13
10.3.3 Communications requirements (CON)

independent

certification
awarded body.

(OPT)

Any quality certification Any necessary communications hardware and software shall be indicated as well as protocol characteristics and constraints. naming the awarding

to the package shall be stated

10.14
10.3.4 Other requirements (CON) shall be indicated.

Product

code

(ES!%

Any item number or product code which Identifies the package or its component items shall be given, for example Universal Product Code, supplier part number, ware Number (SCSN). Standard Computer Soft

Any other environmental

requirements

10.4
The

Input
input

(OPT) 10.15 Price (OPT)
price shall be stated. or medium, for example keyboard, file, The recommended

device

joystick,

mouse,

shall be defined

or illustrated.
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